home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / stk-3.0 / stk-3 / blt-for-STk-3.0 / blt-1.9 / man / bgexec.man < prev    next >
Encoding:
Text File  |  1995-07-01  |  4.7 KB  |  110 lines
  1. '\"
  2. '\" Copyright 1993-1994 by AT&T Bell Laboratories.
  3. '\"
  4. '\" Permission to use, copy, modify, and distribute this software
  5. '\" and its documentation for any purpose and without fee is hereby
  6. '\" granted, provided that the above copyright notice appear in all
  7. '\" copies and that both that the copyright notice and warranty
  8. '\" disclaimer appear in supporting documentation, and that the
  9. '\" names of AT&T Bell Laboratories any of their entities not be used
  10. '\" in advertising or publicity pertaining to distribution of the
  11. '\" software without specific, written prior permission.
  12. '\"
  13. '\" AT&T disclaims all warranties with regard to this software, including
  14. '\" all implied warranties of merchantability and fitness.  In no event
  15. '\" shall AT&T be liable for any special, indirect or consequential
  16. '\" damages or any damages whatsoever resulting from loss of use, data
  17. '\" or profits, whether in an action of contract, negligence or other
  18. '\" tortuous action, arising out of or in connection with the use or
  19. '\" performance of this software.
  20. '\"
  21. '\" Bgexec command created by George Howlett.
  22. '\"
  23. .so man.macros
  24. .HS blt_bgexec cmds
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. blt_bgexec \- Run Unix commands in the background 
  29. .SH SYNOPSIS
  30. \fBblt_bgexec \fR?\fIswitches\fR? \fIvarname arg\fR ?\fIarg\fR ...?
  31. .sp
  32. \fBblt_bgexec \fR?\fIswitches\fR? \fIarg\fR ?\fIarg\fR ...?
  33. .BE
  34. .SH DESCRIPTION
  35. .PP
  36. This command executes one or more Unix
  37. commands in the background as subprocesses, storing the output 
  38. of the last subprocess in the variable \fIvarname\fR after it has completed.  
  39. This allows Unix commands to be run in the background, while still collecting 
  40. their output, to notify the Tcl interpreter when they terminate.
  41. .PP
  42. This command, used in conjunction with \fBtkwait\fR, is particularly useful 
  43. for handling Tk events while waiting for a running UNIX program to finish.
  44. .DS
  45. \fBblt_bgexec \fIvarname command args\fR
  46. .br
  47. \fBtkwait variable\fR \fIvarname\fR
  48. .DE
  49. .PP
  50. This allows expose events can be handled while waiting for one or more 
  51. Unix commands to finish.  The program may also continue, possibly 
  52. animating a busy 
  53. cursor or icon, while waiting for the variable \fIvarname\fR to be set.
  54. After all the subprocesses have completed, \fBblt_bgexec\fR will 
  55. set \fIvarname\fR, triggering \fBtkwait\fR to return.
  56. \fIVarname\fR will contain the output of the last subprocess.
  57. .PP
  58. If the initial arguments to \fBblt_bgexec\fR start with \fB\-\fR then
  59. they are treated as command-line switches and are not part
  60. of the variable name or pipeline specification.  The following 
  61. switches are currently supported:
  62. .TP 13
  63. \fB\-keepnewline
  64. Specifies that a trailing newline should be retained in the pipeline's 
  65. output. Normally a trailing newline will be deleted.  
  66. .TP 13
  67. \fB\-killsignal \fInumber\fR
  68. Specifies the number of the signal to be sent to the Unix subprocesses when 
  69. cleaning up. If \fInumber\fR is \fC0\fR, then no signals are sent.  By 
  70. default, subprocesses are sent signal \fC1\fR (SIGHUP).
  71. .TP 13
  72. \fB\-errorvar \fIstring\fR
  73. Specifies the name of a global variable to be set with the contents of 
  74. standard error after the last subprocess has completed.
  75. .TP 13
  76. \fB\-outputvar \fIstring\fR
  77. Specifies the name of a global variable to be set with the contents of 
  78. standard output after the last subprocess has completed.  If the 
  79. command-line argument \fIvarname\fR is not specified, then this switch 
  80. must be set.
  81. .TP 13
  82. \fB\-statusvar \fIstring\fR
  83. Specifies the name of a global variable to be set with the status
  84. of the last subprocess to complete.  This contents will be a list of 
  85. status information in the form status token, exit code, and description.
  86. .TP 13
  87. \fB\-updatevar \fIstring\fR
  88. Specifies the name of a global variable which is appended with the 
  89. standard output of the last subprocess.  This variable is updated as data 
  90. becomes available (i.e. read from the pipeline), unlike \fIvarname\fR which 
  91. is set \fBafter\fR the last subprocess has completed.
  92. .TP 13
  93. \fB\-\|\-\fR
  94. Marks the end of switches.  The argument following this one will
  95. be treated as the output variable name \fIvarName\fR or the start of 
  96. Unix command even if it starts with 
  97. a \fB\-.
  98. .PP
  99. \fICommand\fR and \fIargs\fR may be in any form accepted by the Tcl \fBexec\fR
  100. command.  You can also prematurely terminate the subprocesses by 
  101. setting \fIvarname\fR 
  102. before the last command has completed.  Each subprocess will be sent
  103. a termination signal (see the \fB-killsignal\fR option).  
  104. .SH BUGS
  105. Care must be taken to prevent an application from preempting itself
  106. by further user-interactions (such as button clicks).  The \fBblt_busy\fR
  107. command is very useful in these situations (see the \fBblt_busy\fR manual).
  108. .SH KEYWORDS
  109. exec, background
  110.